Name

upsf95 - X11 based Fortran 95 debugger

Overview

Upsf95 is the Fortran 90/95 debugger for use with the NAGWare f95 compiler. It is a debugger with a graphical user interface, and is a modified version of the open-source debugger ``ups''.

The program to be debugged should be compiled and linked with the -g option.

Upsf95 runs in its own window, thus not interfering with the user program's I/O. The upsf95 window has two major areas - one showing a structured document representing the state, the other showing the source that is being executed.

Upsf95 needs little documentation for normal use, as its interface is very straightforward. While stepping through the program, the next source line to be executed is shown highlighted in the source code window, and breakpoints are shown interspersed as pseudo-code.

Upsf95 contains the same support for debugging C code as the original ups debugger.

Usage

upsf95 executable-file [core-file|process-id] [-a user-args]

Arguments

executable-file
This is the executable file for the program to be debugged, e.g. ``a.out''. This argument is required.
core-file
This optional argument is a core dump to examine, e.g. ``core''.
process-id
This optional argument indicates an existing process to which to attach upsf95, e.g. ``1077''. The process must already be executing the program to be debugged.
-a user-args
This optional pair of arguments is for passing command-line arguments to the program being debugged, e.g. ``-a arg''. To pass more than one argument, double quotes should be used, e.g. ``-a "arg1 arg2"''. The arguments may be changed from within upsf95, by editing the command line (shown near the top of the upper window); clicking the middle mouse button on this line will edit it.

Example Debugging Session

This section contains a simple example of the use of upsf95 on a small sample Fortran program.

    MODULE fh4
      REAL :: r = -HUGE(0.0)
    END MODULE fh4

    PROGRAM fh4_prog
      USE fh4
      COMMON/fh4com/i
      CALL sub(2)
      PRINT *,i,r
    END PROGRAM fh4_prog

    SUBROUTINE sub(j)
      USE fh4
      COMMON/fh4com/i
      r = 0.5*j
      i = j*3
    END SUBROUTINE sub

Assuming the above code is in the file ``sample.f90'', it may be debugged as follows:

Editable Fields

All editable fields in upsf95 work in the same way. To start editing you click the middle mouse button over the editable text. A black ``marker bar'' appears - characters that you type appear to the left of this marker bar. You can reposition the marker bar by clicking in the new position with the middle mouse button, or by using one of the cursor movement key sequences described below.

Clicking the left or right button confirms the edit. Clicking the middle mouse button outside the editable text area also confirms the edit. In both cases the mouse click is then interpreted as normal - this means that to confirm an edit you can simply move on to another activity. The final way to confirm an edit is to type ESC (the escape key) or click the left mouse button on the Enter Button (the small region to the right of the typing line with the "<<" image).

To paste the current window system cut buffer, use Control-Y or click the middle mouse button on the Enter Button.

When you try to confirm an edit, upsf95 checks that the new field value is reasonable. If not you get an error message and you are left in the edit. An immediate second attempt to quit abandons the edit and restores the original field value.

When editing, upsf95 uses similar command keys to emacs. These key bindings are:

Control-A Move to start of line
Control-B, LEFT Move backwards one character
Control-C Cancel edit (not an emacs binding)
Control-D Delete character forwards
Control-E Move to end of line
Control-F, RIGHT Move forward one character
Control-K Delete to end of line
Control-N, DOWN Move down a line, if possible, otherwise retrieve the next later item in the history buffer
Control-P, UP Move up a line, if possible, otherwise retrieve the next previous item in the history buffer
Control-U Delete to start of line (not an emacs binding)
Control-W Delete text between mark and point
Control-Y Paste X selection
Alt-@, Alt-space Set mark
Alt-B Move backwards one word
Alt-D Delete word forwards
Alt-F Move forward one word
Alt-M Move to first non-whitespace character
Alt-Delete Delete word backwards
Delete Delete character backwards
Escape Finish edit
Return In an editable field, finish the edit. In the source window, start a new line.
Alt-> Move to end of buffer
Alt-< Move to start of buffer

If you run upsf95 from a terminal (or a terminal emulator like xterm), it tries to discover what keys you are using for delete and line erase. If this fails it takes both ^H (backspace) and DEL to mean delete, and ^U to mean line erase.

Edit History

Most of the editable fields in upsf95 have their own history of recently typed commands. For example, there is a history of typing line commands, a history of breakpoint code entered, and a history of variable values changed.

Pressing the Left mouse button on the History Button, the small region to the right of the typing line with the triangular image, pops up a menu of recently entered data for that field.

When editing most single line fields, a Control-P, or up arrow moves the history pointer back one entry and replaces the current text with the previous entry. Typing a Control-N, or down arrow, moves the history pointer forward one entry.

Edit histories are saved between sessions of upsf95 in ups-state/editHistory, if you use the ups-state feature, or in the file ~/.upsEditHistory if not.

Cut and Paste

Text can be selected by holding the left mouse button down and moving the cursor. Selected text will be highlighted. Releasing the button sets the selection.

Selected text can be pasted into an edit with Control-Y or by clicking the middle mouse button on the Enter Button (the small region to the right of the typing line with the ``<<'' image).

Note that in the source window, left-clicking on a variable name (without dragging) adds the variable name to the stack frame display; only if the mouse is moved is the text made into a plain X selection (and not added to the stack frame display unless the Shift key was also being held down).

Signals

When the target gets a signal control returns to upsf95. Depending on the signal and the way you have specified it should be handled, the target is either stopped or restarted (possibly with a display refresh), and the signal can either be passed on to the target or ignored. Signal handling can be controlled using the ``Signals'' object in the display area.

X11 Command Line Arguments

Upsf95 recognises many common X11 command line arguments. These include:

-display displayname
Create a window on the named display rather than using the value of the DISPLAY environment variable.
-bg colourspec
Use colourspec as the background colour.
-geometry geometry
Use the specified X geometry for the window.
-fg colourspec
Use colourspec as the foreground colour.
-fn fontname
Use font fontname instead of the default.
-iconic
Start up as an icon rather than as a window.
-name name
Use name rather than the default upsf95 as the window and icon name. This name is also used when fetching X defaults.

X11 Resources

The appearance of upsf95 is controlled by the use of X11 resources with the prefix ``upsf95'', or if that is not found, ``Ups''. The default appearance if no resource is found is taken from the file ``Ups'' in the NAGWare f95 compiler library directory. See the ups documentation for a full list of recognised X11 resources.

Using a Single-button Mouse

On the Apple Mac OS X only, where this document says ``left click'', this is a normal mouse click. Where it says ``middle click'', hold the Alt key down and click. Where it says ``right click'', hold the Apple key down and click.

See Also

f95(1), ups(1), http://ups.sourceforge.net/main.html.

Bugs

Please report any bugs found to ``support@nag.co.uk'' or ``infodesk@nag.com'', along with any suggestions for improvements.